<!--
  // Ubiquity provides a standards-based suite of browser enhancements for
  // building a new generation of internet-related applications.
  //
  // The Ubiquity XForms module adds XForms 1.1 support to the Ubiquity
  // library.
  //
  // Copyright (C) 2008-9 Backplane Ltd.
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //  http://www.apache.org/licenses/LICENSE-2.0
  //
  // Unless required by applicable law or agreed to in writing, software
  // distributed under the License is distributed on an "AS IS" BASIS,
  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  // See the License for the specific language governing permissions and
  // limitations under the License.
-->
<html
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:ev="http://www.w3.org/2001/xml-events"
  xmlns:xf="http://www.w3.org/2002/xforms"
>
	<head>
	  <title>Using XForms hint</title>
		<script src="../../deploy/backplanejs-0.6.4/backplane-min.js" type="text/javascript">/**/</script>
		<link rel="stylesheet" href="../../deploy/backplanejs-0.6.4/assets/backplane-min.css" />
	  <style type="text/css">
	    .sample {
  	    border: 1px solid silver;
  	    background-color: lightyellow;
  	    padding: 30px;
  	    margin-left: 30px;
  	    width: 85%;
	    }
	    pre {
  	    background-color: black;
  	    color: green;
  	    padding: 5px;
  	    overflow: auto;
  	    padding: 30px;
  	    margin-left: 30px;
  	    width: 85%;
  	  }
     .danger {
	      background: red url(images/exclamation.png) no-repeat 5px;
	      padding-left: 48px;
	      height: 2em;
	      width: 300px;
     }
     xf\:input.indent xf\:hint {
       margin-left: 200px;
     }
	  </style>
	</head>
  <body>
    <xf:model>
      <xf:instance>
        <data>
          <firstname>Mickey</firstname>
          <surname>Mouse</surname>
          <age>80</age>
        </data>
      </xf:instance>
    </xf:model>

    <h1>Using XForms hint</h1>
    <p>
      The XForms <code>hint</code> element is used by form authors to provide some
      extra text that will be used to help people complete their forms. The text
      is displayed when the user places their mouse over a control, and disappears
      automatically, 10 seconds later. The message is also removed if the user moves
      their mouse away or clicks on the control to start entering data.
    </p>
    <p>
      For each of the examples we have below, there is both the markup and a live
      version of the code; so move your mouse over the various controls to see
      how the markup behaves.
    </p>
    <p>
      (The exclamation icon is from <a href="http://jonasraskdesign.com">Jonas Rask</a>.)
    </p>
    <h2>The basic format</h2>
    <p>
      A simple example is to add a hint that uses inline text, like this:
      <pre>
&lt;xf:trigger>
  &lt;xf:label>Delete all records&lt;/xf:label>
  &lt;xf:hint>This will remove all of your records!&lt;/xf:hint>
&lt;/xf:trigger>
      </pre>
      <div class="sample">
        <xf:trigger>
          <xf:label>Delete all records</xf:label>
          <xf:hint>This will remove all of your records!</xf:hint>
        </xf:trigger>
      </div>
    </p>
    <h2>Adding HTML markup</h2>
    <p>
      The text in a hint can be any HTML markup, such as text formatting:
      <pre>
&lt;xf:trigger>
  &lt;xf:label>Delete all records&lt;/xf:label>
  &lt;xf:hint>This will remove &lt;em>all&lt;/em> of your records!&lt;/xf:hint>
&lt;/xf:trigger>
      </pre>
      <div class="sample">
        <xf:trigger>
          <xf:label>Delete all records</xf:label>
          <xf:hint>This will remove <em>all</em> of your records!</xf:hint>
        </xf:trigger>
      </div>
      or images:
      <pre>
&lt;xf:trigger>
  &lt;xf:label>Delete all records&lt;/xf:label>
  &lt;xf:hint>
    This will remove &lt;em>all&lt;/em> of your records!
    &lt;img src="images/exclamation.png" />
	&lt;/xf:hint>
&lt;/xf:trigger>
      </pre>
      <div class="sample">
        <xf:trigger>
          <xf:label>Delete all records</xf:label>
          <xf:hint>
            This will remove <em>all</em> of your records!
            <img src="images/exclamation.png" />
          </xf:hint>
        </xf:trigger>
      </div>
    </p>

    <h2>Styling the hint</h2>
    <p>
      Since the hint itself is simply an inline element, it can be styled like any other.
      For example, to set the width and background of the hint, we might do this:
      <pre>
&lt;xf:trigger>
  &lt;xf:label>Delete all records&lt;/xf:label>
  &lt;xf:hint style="background-color: red; width: 300px;">
    This will remove &lt;em>all&lt;/em> of your records!
    &lt;img src="images/exclamation.png" />
  &lt;/xf:hint>
&lt;/xf:trigger>
      </pre>
      <div class="sample">
        <xf:trigger>
          <xf:label>Delete all records</xf:label>
          <xf:hint style="background-color: red; width: 300px;">
            This will remove <em>all</em> of your records!
            <img src="images/exclamation.png" />
          </xf:hint>
        </xf:trigger>
      </div>
    </p>
    <p>
      Of course, you'll generally want to use rules in stylesheets, rather than applying
      style directly to an element. For example, the red background and exclamation image
      we just saw could be used on all hints with a class of 'danger', by setting up rules
      for the CSS class:
      <pre>
&lt;style type="text/css">
  .danger {
    background: red url(images/exclamation.png) no-repeat 5px;
    padding-left: 48px;
    height: 2em;
    width: 300px;
  }
&lt;/style>
      </pre>
      and then using the class name on the <code>hint</code>:
      <pre>
&lt;xf:trigger>
  &lt;xf:label>Delete all records&lt;/xf:label>
  &lt;xf:hint class="danger">
    This will remove &lt;em>all&lt;/em> of your records!
  &lt;/xf:hint>
&lt;/xf:trigger>
      </pre>
      <div class="sample">
        <xf:trigger>
          <xf:label>Delete all records</xf:label>
          <xf:hint class="danger">
            This will remove <em>all</em> of your records!
          </xf:hint>
        </xf:trigger>
      </div>
    </p>
    <p>
      This technique is useful for formatting hints in different
      ways for different controls. For example, a hint on an input control is normally shown
      just below the control's label:
      <pre>
&lt;xf:input ref="firstname">
  &lt;xf:label>Forename:&lt;/xf:label>
  &lt;xf:hint>Please enter your first name&lt;/xf:hint>
&lt;/xf:input>
      </pre>
      <div class="sample">
        <xf:input ref="firstname">
          <xf:label>Forename:</xf:label>
          <xf:hint>Please enter your first name</xf:hint>
        </xf:input>
      </div>
    </p>
    <p>
      However, by adding a left margin on all hints that are attached to an input control, we
      can offset the position of the hint by the same amount as the label, so that it lines up
      with the data entry area:
      <pre>
&lt;style type="text/css">
  xf\:input xf\:hint {
    margin-left: 200px;
  }
&lt;/style>

&lt;xf:input ref="surname">
  &lt;xf:label>Surname:&lt;/xf:label>
  &lt;xf:hint>Please enter your surname&lt;/xf:hint>
&lt;/xf:input>
      </pre>
      <div class="sample">
        <xf:input ref="surname" class="indent">
          <xf:label>Surname:</xf:label>
          <xf:hint>Please enter your surname</xf:hint>
        </xf:input>
      </div>
    </p>
    <h2>Adding XForms markup</h2>
    <p>
      Finally, just as we can add HTML markup to the hint, we can also add XForms markup:
      <pre>
&lt;xf:input ref="age">
  &lt;xf:label>Age:&lt;/xf:label>
  &lt;xf:hint>
    Please enter &lt;xf:output value="concat(../firstname, ' ', ../surname)">&lt;/xf:output>'s age
  &lt;/xf:hint>
&lt;/xf:input>
      </pre>
      Note how the text in the hint comes from the values in the two controls, above. Changing the values
      above will also change the text of the hint.
      <div class="sample">
        <xf:input ref="age" class="indent">
          <xf:label>Age:</xf:label>
          <xf:hint>
            Please enter <xf:output value="concat(../firstname, ' ', ../surname)" style="color: black;"></xf:output>'s age
          </xf:hint>
        </xf:input>
      </div>
    </p>
    <h2>Further reading</h2>
    <p>
      For more information see the <a href="http://www.w3.org/TR/xforms11/#ui-commonelems-hint">definition of hint
        in the XForms 1.1 specification</a>.
    </p>
  </body>
</html>
